---
title: "Using the CLI"
description: "How to start a bknd instance using the CLI."
icon: Terminal
tags: ["documentation"]
---

The bknd package includes a command-line interface (CLI) that allows you to run a bknd instance and perform various tasks.

```sh
npx bknd
```

Here is the output:

```sh
$ npx bknd
Usage: bknd [options] [command]

Options:
  -V, --version          output the version number
  -h, --help             display help for command

Commands:
  config [options]         get app config
  copy-assets [options]    copy static assets
  create [options]         create a new project
  debug <subject>          debug bknd
  mcp [options]            mcp server stdio transport
  run [options]            run an instance
  schema [options]         get schema
  sync [options]           sync database
  types [options]          generate types
  user [options] <action>  create/update users, or generate a token (auth)
  help [command]           display help for command
```

## Starting an instance (`run`)

To see all available `run` options, execute `npx bknd run --help`.

```sh
$ npx bknd run --help
Usage: bknd run [options]

Options:
  -p, --port <port>      port to run on (default: 1337, env: PORT)
  -m, --memory           use in-memory database
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid libsql url
  --db-token <db>        database token
  --server <server>      server type (choices: "node", "bun", default: "bun")
  --no-open              don't open browser window on start
  -h, --help             display help for command
```

To order in which the connection is determined is as follows:

1. `--db-url`
2. `--config` or reading the filesystem looking for `bknd.config.[js|ts|mjs|cjs|json]`
3. `--memory`
4. Environment variables `DB_URL` and `DB_TOKEN` in `.env` or `.dev.vars`
5. Fallback to file-based database `data.db`

### File-based database

By default, a file-based database `data.db` is used when running without any arguments. You can specify a different file name or path using the `--db-url` option. The database file will be created in the current working directory if it does not exist.

```
npx bknd run --db-url file:data.db
```

### Using configuration file (`bknd.config.*`)

You can create a configuration file on the working directory that automatically gets picked up: `bknd.config.[js|ts|mjs|cjs|json]`

Here is an example of a `bknd.config.ts` file:

```ts
import type { BkndConfig } from "bknd/adapter";

export default {
  // you can either specify the connection directly
  connection: {
    url: "file:data.db",
  },
  // or use the `app` function which passes the environment variables
  app: (env) => ({
    connection: {
      url: env.DB_URL,
    },
  }),
} satisfies BkndConfig;
```

The `app` function is useful if you need a cross-platform way to access the environment variables. For example, on Cloudflare Workers, you can only access environment variables inside a request handler. If you're exclusively using a node-like environment, it's safe to access the environment variables directly from `process.env`.

If you're using `npx bknd run`, make sure to create a file in a file format that `node` can load, otherwise you may run into an error that the file couldn't be found:

```
[INF] 2025-03-28 18:02:21 Using config from bknd.config.ts
[ERR] 2025-03-28 18:02:21 Failed to load config: Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'bknd.config.ts' imported from [...]
    at packageResolve (node:internal/modules/esm/resolve:857:9)
    at [...] {
  code: 'ERR_MODULE_NOT_FOUND'
}
```

If you still want to use a `.ts` extension, you can start the CLI e.g. using `node` (>=v22.6.0):

```sh
node --experimental-strip-types node_modules/.bin/bknd run
```

Or with `tsx`:

```sh
npx tsx node_modules/.bin/bknd run
```

### Turso/LibSQL database

To start an instance with a Turso/LibSQL database, run the following:

```sh
npx bknd run --db-url libsql://your-db.turso.io --db-token <your-token>
```

The `--db-token` option is optional and only required if the database is protected.

### In-memory database

To start an instance with an ephemeral in-memory database, run the following:

```sh
npx bknd run --memory
```

Keep in mind that the database is not persisted and will be lost when the process is terminated.

## Generating types (`types`)

To see all available `types` options, execute `npx bknd types --help`.

```sh
$ npx bknd types --help
Usage: bknd types [options]

generate types

Options:
  -o, --outfile <outfile>  output file (default: "bknd-types.d.ts")
  --no-write               do not write to file
  -h, --help               display help for command
```

To generate types for the database, run the following:

```sh
npx bknd types
```

This will generate types for your database schema in `bknd-types.d.ts`. The generated file could look like this:

```typescript title="bknd-types.d.ts"
import type { DB } from "bknd";
import type { Insertable, Selectable, Updateable, Generated } from "kysely";

declare global {
  type BkndEntity<T extends keyof DB> = Selectable<DB[T]>;
  type BkndEntityCreate<T extends keyof DB> = Insertable<DB[T]>;
  type BkndEntityUpdate<T extends keyof DB> = Updateable<DB[T]>;
}

export interface Todos {
  id: Generated<number>;
  title?: string;
  done?: boolean;
}

interface Database {
  todos: Todos;
}

declare module "bknd" {
  interface DB extends Database {}
}
```

Make sure to add the generated file in your `tsconfig.json` file:

```json title="tsconfig.json"
{
  "include": ["bknd-types.d.ts"]
}
```

You can then use the types by importing them from `bknd`:

```typescript
import type { DB } from "bknd";

type Todo = DB["todos"];
```

All bknd methods that involve your database schema will be automatically typed. You may use the [`syncTypes`](/extending/plugins/#synctypes) plugin to automatically write the types to a file.

## Getting the configuration (`config`)

To see all available `config` options, execute `npx bknd config --help`.

```sh
$ npx bknd config --help
Usage: bknd config [options]

get app config

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --pretty               pretty print
  --default              use default config
  --secrets              include secrets in output
  --out <file>           output file
  -h, --help             display help for command
```

To get the configuration of your app, and to write it to a file, run the following:

```sh
npx bknd config --out appconfig.json
```

To get a template configuration instead, run the following:

```sh
npx bknd config --default
```

To automatically sync your configuration to a file, you may also use the [`syncConfig`](/extending/plugins/#syncconfig) plugin.

## Getting the secrets (`secrets`)

To see all available `secrets` options, execute `npx bknd secrets --help`.

```sh
$ npx bknd secrets --help
Usage: bknd secrets [options]

get app secrets

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --template             template output without the actual secrets
  --format <format>      format output (choices: "json", "env", default:
                         "json")
  --out <file>           output file
  -h, --help             display help for command
```

To automatically sync your secrets to a file, you may also use the [`syncSecrets`](/extending/plugins/#syncsecrets) plugin.

## Syncing the database (`sync`)

Sync your database can be useful when running in [`code`](/usage/introduction/#code-only-mode) mode. When you're ready to deploy, you can point to the production configuration and sync the database. Schema mutations are only applied when running with the `--force` option.

```bash
$ npx bknd sync --help
Usage: bknd sync [options]

sync database

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --seed                 perform seeding operations
  --force                perform database syncing operations
  --drop                 include destructive DDL operations
  --out <file>           output file
  --sql                  use sql output
  -h, --help             display help for command
```

